----------------------------------------------------------------
Collection Hole Finder v1.0.0
June, 2007
----------------------------------------------------------------

======
INDEX:
======
 1. Quick Start
 2. Authors
 3. Introduction
 4. Contents
 5. Usage
 6. How to create an input file
 7. System Requirements
 8. FAQ
 9. Special thanks
10. Contact
11. To Do List (Known Issues)

===========
Quick Start:
===========
Type "CollectionHoleFinder -h" at a command prompt to display usage help.

========
Authors:
========
Adam Sternberg <sternber@bellsouth.net>

=============
Introduction:
=============
Collection Hole Finder came about as effort to enhance ComicBase's ability
to list issues missing from a collection (essentially, issues having a
Quantity value of 0).  While the ComicBase Issue Checklist report applied
to missing issues is useful, it is often overwhelmingly large, especially
when considering some older titles, such as Action Comics.  While any collector
will determine that any missing issue is a hole that needs to be filled, I
determined that a pragmatic solution was needed, and decided that I would
focus on filling holes of finite size.

What is a hole?  A hole is a grouping of missing issues between issues owned.  
For example, if I own issues 1 and 5, then the hole is issues 2-4.  I settled 
on a hole size of 5 issues or less.  If I own issues 1 and 5, then I'd try to 
buy issues 2, 3, and 4 eventually.  However, if I own issues 1 and 7, then forget 
about issues 2-6.

Once that decision was made, I could export the missing issues checklist just
for those titles I had "in stock" into a spreadsheet and start deleting issues
that didn't fit into a small enough hole.  However, that still meant whittling
a report of thousands of issues down to one of tens of issues by hand.  Since
I'm a programmer for a living, it seemed natural to create a program to parse
the text file output from ComicBase.  And so, Collection Hole Finder was born.

Later on, in the ComicBase forums, others posted with similar frustrations,
and it was requested that Collection Hole Finder be shared with other collectors.
I was encourage to share the source code with the users, in the hopes that they
could recommend (or even code up) enhancements to the program.  Please see the
"Contact" section to recommend enhancements or share changes.

Collection Hole Finder is published under the GNU General Public License (GPL),
is distributed as-is, and cannot be bundled into a proprietary application.  
Refer to LICENSE.txt or http://www.gnu.org/licenses/gpl-faq.html for an FAQ
about the GPL.

=========
Contents:
=========
The following files were distributed as part of this package:
* CollectionHoleFinder.exe    - The Collection Hole Finder executable
* Collection Hole Finder.cpp  - The main source code file
* MyGetOpt.cpp                - Source code for command line processing
* MyGetOpt.h                  - Header file for command line processing
* StdAfx.cpp                  - Source code for including a pre-compiled header
* StdAfx.h                    - Header file for including a pre-compiled header
* Collection Hole Finder.mak  - Makefile used to build the executable
* Collection Hole Finder.dep  - Pre-built dependencies file used in building
* README.txt                  - This file
* LICENSE.txt                 - A copy of the GNU General Public License
* master issue checklists.csv - A sample input file

======
Usage:
======
The following is an overview of the command line options you can pass to 
Collection Hole Finder.  Collection Hole Finder must be executed from a 
command prompt (cmd.exe) or create a shortcut to CollectionHoleFinder.exe
(setting the command line options and working directory properly).

The input file is expected to be a comma-separated value file (CSV) of a
certain format (see "How to create an input file" below), and the output
file is a filtered version of the input file (also CSV).  The output file
can then be opened in any standard editor, word processor, or perhaps most
useful, a spreadsheet or database program, for processing.  Options may be
listed in any order and aside from the -n option, options listed multiple
times will only recognize the last parameter given.

Collection Hole Finder may be executed as follows:

	CollectionHoleFinder -h | -? | --help
	CollectionHoleFinder -i <input file> -o <output file> [-s <size> | --hole <size>]
								[-l <log file> | --log <log file>]
								[-n <type> | --ignore <type> [-n <type> | --ignore <type>]...]
	
-i <input file>
--input <input file>
   The name of the file to search for collection holes in.  This file is 
   generated from ComicBase as described in "How to create an input file" 
   below.  The switch "--input" may be used in place of "-i".  This switch 
   is mandatory.
    
-o <output file>
--output <output file>
   The name of the file to contain the filtered list of missing issues.  
   The switch "--output" may be used in place of "-o".  This switch is 
   mandatory.
    
-l <log file>
--log <log file>
   The name of the log file used to store processing messages.  Processing 
   messages are written both to screen and to the log file.  The default file 
   is ComicHoles.log.  The switch "--log" may be used in place of "-l".
    
-s <size>
--hole <size>
   The size of the missing issue hole to be kept.  The default value is 4.  
   The switch "--hole" may be used in place of "-s".
    
-n <issue type>
--ignore <issue type>
   This switch tells Collection Hole Finder to ignore the given issue type.  
   For example, to filter out all issues of type "Bk", use "-n Bk" or 
   "--ignore Bk" as part of the command line options.  This option may be listed 
   multiple times to ignore several issue types (for example, "-n Bk -n Ash" to 
   remove issues of either type "Bk" or type "Ash").  The switch "--ignore" may be 
   used in place of "-n".
    
-h
-?
--help
   Display help information and exit.

Note: If a parameter contains a space in it, put the enter string between double 
	quotes (For example, -o "Missing Issues June 2007.csv").

============================
How to create an input file:
============================
Collection Hole Finder expects input files to be CSV files with the fields 
corresponding to an issue checklist report from ComicBase.  To create such
a report, do the following:
 1. In ComicBase, select "Issue Checklists" from the Report menu.
 2. In the Print dialog box that pops up, select "Missing issues of each title"
    and de-select "Issues of each title", "Include storylines, artists, and
    writers", and any custom fields.
 3. Select the issues to be included in the report as documented in ComicBase.
 4. Click the "Preview..." button to generate the report and display it on screen.
    NOTE: Do not choose the "Export..." button.
 5. Click OK on the Print Setup dialog box.
 6. Click the export button to bring up the Export dialog box.
 7. Select "Separated Values (CSV) as the format and "Disk File" as the destination.
 8. In the Character-Separated Values dialog box, select Tab as the separator and " 
    as the delimiter.  Click "OK".
 9. In the Number and Date Format Settings dialog box, select both the "Same number 
    formats as in report" and "Same date formats as in report" checkboxs.  Click
    "OK".
10. Choose a destination file for the export and begin.  The destination file is the
    input file to Collection Hole Finder.

====================
System requirements:
====================
Collection Hole Finder was compiled using Microsoft Visual Studio 6.0 and tested on a 
Windows 2000 machine.  It should run on any machine capable of running Windows 95 
or later.

====
FAQ:
====
Some Frequently Asked Questions:

Q: I've got a variant printing of an issue, but the other versions of the
	issue show up in the output file.

Q: I've got a variant printing of an issue, but the other versions of the
	issue show up in the output file.
A: This is a known issue (see To Do List below for a description of the 
	problem).  Any suggestions on a solution are most welcome.

For answers to more questions, read the remainder of this README and/or check 
the ComicBase Community home page and forums.

===============
Special Thanks:
===============
Pete Bickford of Human Computing for his support and guidance in distributing 
	this program.
Brian Dominy for his guidance in distributing shareware under GPL.
And, of course, the Human Computing team for a little program called ComicBase.

========
Contact:
========
Support: Adam Sternberg (sternber@bellsouth.net)
ComicBase: http://www.comicbase.com

For more information on this and other ComicBase-related tools,
see the site http://www.atomicavenue.com/Community.asp

ComicBase community forums can be found at the site
http://www.atomicavenue.com/forum/default.asp

==========================
To Do List (Known Issues):
==========================
* Collection Hole Finder will not determine an issue is
	owned if a variant is owned, but the original is not.
	Consider the following example:
		Title1 has issues 1, 1/A, and 2
		Title2 has issues 1 and 2
		The user owns Title1 1/A, so the missing issues report will look like
		this:
			Title1 1, Title1 2, Title2 1, Title2 2
		The proper output would be
			Title1 2, Title2 1, and Title2 2
		However, there's no way of knowing whether Title1 1/A is owned or doesn't
		exist.
		
* Add support for a configuration file, so multiple options used on a 
	more-or-less permanent basis don't have to be keyed in on the command
	line each time.
	
